<HTML>
<HEAD>
<TITLE>[Chapter 10] 10.4 MenuItem</TITLE>
<META NAME="author" CONTENT="John Zukowski">
<META NAME="date" CONTENT="Thu Jul 31 14:46:18 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java AWT">
<META NAME="title" CONTENT="Java AWT">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java AWT" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch10_03.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 10<br>Would You Like to Choose from the Menu?</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch10_05.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JAWT-CH-10-SECT-4">10.4 MenuItem</A></h2>

<P CLASS=para>
<A NAME="CH10.ITEM1"></A>A <tt CLASS=literal>MenuItem</tt> is the basic item 
that goes on a <tt CLASS=literal>Menu</tt>. Menus 
themselves are menu items, allowing submenus to be nested inside of menus. 
<tt CLASS=literal>MenuItem</tt> is a subclass of <tt CLASS=literal>MenuComponent</tt>. 

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JAWT-CH-10-SECT-4.1">MenuItem Methods</A></h3>Constructors

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public MenuItem () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The first <tt CLASS=literal>MenuItem</tt> constructor 
creates a <tt CLASS=literal>MenuItem</tt> with an 
empty label and no keyboard shortcut. To set the label at later time, use 
<tt CLASS=literal>setLabel()</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public MenuItem (String label) </I><br>
<DD>

<P CLASS=para>
This <tt CLASS=literal>MenuItem</tt> constructor creates 
a <tt CLASS=literal>MenuItem</tt> with a label of 
<tt CLASS=literal>label</tt> and no keyboard shortcut. 
A label of "-" represents a separator. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public MenuItem (String label, MenuShortcut shortcut) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The final <tt CLASS=literal>MenuItem</tt> constructor 
creates a <tt CLASS=literal>MenuItem</tt> with a label 
of <tt CLASS=literal>label</tt> and a <tt CLASS=literal>MenuShortcut</tt> 
of <tt CLASS=literal>shortcut</tt>. Pressing the shortcut 
key is the same as selecting the menu item. </DL>
Menu labels

<P CLASS=para>
Each <tt CLASS=literal>MenuItem</tt> has a label. 
This is the text that is displayed on the menu. 

<DIV CLASS=note>
<P CLASS=note><BLOCKQUOTE><P><B>NOTE:</B> 
</blockquote><P>
</DIV>

<P CLASS=para>
Prior to Java 1.1, there was no portable way to associate a hot key 
with a <tt CLASS=literal>MenuItem</tt>. However, in Java 1.0, if 
you precede a character with an &amp; on a Windows platform, it will appear 
underlined, and that key will act as the menu's mnemonic key (a different type of 
shortcut from <tt CLASS=literal>MenuShortcut</tt>). 
Unfortunately, on a Motif platform, the user will see the &amp;. Because 
the &amp; is part of the label, even if it is not displayed, you must include 
it explicitly whenever you compare the label to a string. 
</blockquote><P>
</DIV>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public String getLabel () </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getLabel()</tt> method retrieves 
the label associated with the <tt CLASS=literal>MenuItem</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setLabel (String label) </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setLabel()</tt> method changes 
the label of the <tt CLASS=literal>MenuItem</tt> to 
<tt CLASS=literal>label</tt>. </DL>
Shortcuts

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public MenuShortcut getMenuShortcut () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getMenuShortcut()</tt> method 
retrieves the shortcut associated with this <tt CLASS=literal>MenuItem</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setShortcut (MenuShortcut shortcut) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setShortcut()</tt> method allows 
you to change the shortcut associated with a <tt CLASS=literal>MenuItem</tt> 
to <tt CLASS=literal>shortcut</tt> after the <tt CLASS=literal>MenuItem</tt> 
has been created. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void deleteMenuShortcut () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>deleteMenuShortcut()</tt> method 
removes any associated <tt CLASS=literal>MenuShortcut</tt> 
from the <tt CLASS=literal>MenuItem</tt>. If there 
was no shortcut, nothing happens. </DL>
Enabling

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public boolean isEnabled () </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>isEnabled()</tt> method checks 
to see if the <tt CLASS=literal>MenuItem</tt> is currently 
enabled. An enabled <tt CLASS=literal>MenuItem</tt> 
can be selected by the user. A disabled <tt CLASS=literal>MenuItem</tt>, 
by convention, appears grayed out on the <tt CLASS=literal>Menu</tt>. 
Initially, each <tt CLASS=literal>MenuItem</tt> is 
enabled. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public synchronized void setEnabled(boolean b) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br><I CLASS=emphasis>public void enable (boolean condition) <img src="gifs/wstar.gif" alt="(Deprecated)" border=0></I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setEnabled()</tt> method either 
enables or disables the <tt CLASS=literal>MenuItem</tt> 
based on the value of <tt CLASS=literal>condition</tt>. 
If <tt CLASS=literal>condition</tt> is <tt CLASS=literal>true</tt>, 
the <tt CLASS=literal>MenuItem</tt> is enabled. If 
<tt CLASS=literal>condition</tt> is <tt CLASS=literal>false</tt>, 
it is disabled. When enabled, the user can select it, generating <tt CLASS=literal>ACTION_EVENT</tt> 
or notifying the <tt CLASS=literal>ActionListener</tt>. 
When disabled, the peer does not generate an <tt CLASS=literal>ACTION_EVENT</tt> 
if the user tries to select the <tt CLASS=literal>MenuItem</tt>. 
A disabled <tt CLASS=literal>MenuItem</tt> is usually 
grayed out to signify its state. The way that disabling is signified is platform 
specific. 

<P CLASS=para>
<tt CLASS=literal>enable()</tt> is the Java 1.0 name 
for this method. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public synchronized void enable () <img src="gifs/wstar.gif" alt="(Deprecated)" border=0></I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>enable()</tt> method enables 
the <tt CLASS=literal>MenuItem</tt>. In Java 1.1, 
it is better to use <tt CLASS=literal>setEnabled()</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public synchronized void disable () <img src="gifs/wstar.gif" alt="(Deprecated)" border=0></I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>disable()</tt> method disables 
the component so that the user cannot select it. In Java 1.1, it is better 
to use <tt CLASS=literal>setEnabled()</tt>. </DL>
Miscellaneous methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public synchronized void addNotify ()  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>addNotify()</tt> method creates 
the <tt CLASS=literal>MenuItem</tt> peer. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public String paramString ()</I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>paramString()</tt> method of 
<tt CLASS=literal>MenuItem</tt> should be protected 
like other <tt CLASS=literal>paramString()</tt> methods. 
However, it is public so you have access to it. When you call the <tt CLASS=literal>toString()</tt> 
method of a <tt CLASS=literal>MenuItem</tt>, the default 
<tt CLASS=literal>toString()</tt> method of <tt CLASS=literal>MenuComponent</tt> 
is called. This in turn calls <tt CLASS=literal>paramString()</tt> 
which builds up the string to display. At the <tt CLASS=literal>MenuItem</tt> 
level, the current label of the object and the shortcut (if present) is 
appended to the output. If the constructor for the <tt CLASS=literal>MenuItem</tt> 
was <tt CLASS=literal>new MenuItem(`File`)</tt>, 
the results of <tt CLASS=literal>toString()</tt> would 
be: </DL>
<DIV CLASS=screen>
<P>
<PRE>
java.awt.MenuItem[label=File]
</PRE>
</DIV>

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JAWT-CH-10-SECT-4.2">MenuItem Events</A></h3><A NAME="CH10.EVENT1"></A><A NAME="CH10.EVENT1A"></A> Event handling

<P CLASS=para>
With 1.0 event handing, a <tt CLASS=literal>MenuItem</tt> 
generates an <tt CLASS=literal>ACTION_EVENT</tt> when 
it is selected. The argument to <tt CLASS=literal>action()</tt> 
will be the label of the <tt CLASS=literal>MenuItem</tt>. 
But the target of the <tt CLASS=literal>ACTION_EVENT</tt> 
is the <tt CLASS=literal>Frame</tt> containing the 
menu. You cannot subclass <tt CLASS=literal>MenuItem</tt> 
and catch the <tt CLASS=literal>Event</tt> within 
it with <tt CLASS=literal>action()</tt>, but you can 
with <tt CLASS=literal>postEvent()</tt>. No other 
events are generated for <tt CLASS=literal>MenuItem</tt> 
instances. 

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public boolean action (Event e, Object o)--overridden by user, called by 
system </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>action()</tt> method for a <tt CLASS=literal>MenuItem</tt> 
signifies that the user selected it. <tt CLASS=literal>e</tt> 
is the <tt CLASS=literal>Event</tt> instance for the 
specific event, while <tt CLASS=literal>o</tt> is 
the label of the <tt CLASS=literal>MenuItem</tt>. </DL>
Listeners and 1.1 event handling

<P CLASS=para>
With the 1.1 event model, you register listeners, and they are told when 
the event happens. 

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public String getActionCommand() <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getActionCommand()</tt> method 
retrieves the command associated with this <tt CLASS=literal>MenuItem</tt>. 
By default, it is the label. However, the default can be changed by using 
the <tt CLASS=literal>setActionCommand()</tt> method (described next). The command acts like the second parameter to the <tt CLASS=literal>action()</tt> 
method in the 1.0 event model. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setActionCommand(String command) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setActionCommand()</tt> method 
changes the command associated with a <tt CLASS=literal>MenuItem</tt>. 
When an <tt CLASS=literal>ActionEvent</tt> happens, 
the <tt CLASS=literal>command</tt> is part of the 
event. By default, this would be the label of the <tt CLASS=literal>MenuItem</tt>. 
However, you can change the action command by calling this method. Using 
action commands is a good idea, particularly if you expect your code to 
run in a multilingual environment. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void addActionListener(ItemListener listener) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>addActionListener()</tt> method 
registers <tt CLASS=literal>listener</tt> as an object 
interested in being notified when an <tt CLASS=literal>ActionEvent</tt> 
passes through the <tt CLASS=literal>EventQueue</tt> 
with this <tt CLASS=literal>MenuItem</tt> as its target. 
The <tt CLASS=literal>listener.actionPerformed()</tt> 
method is called whenever these events occur. Multiple listeners can be 
registered. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void removeActionListener(ItemListener listener) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>removeActionListener()</tt> 
method removes <tt CLASS=literal>listener</tt> as 
an interested listener. If <tt CLASS=literal>listener</tt> 
is not registered, nothing happens. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>protected final void enableEvents(long eventsToEnable) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
Using the <tt CLASS=literal>enableEvents()</tt> method 
is usually not necessary. When you register an action listener, the <tt CLASS=literal>MenuItem</tt> 
listens for action events. However, if you wish to listen for events when 
listeners are not registered, you must enable the events explicitly by 
calling this method. The settings for the <tt CLASS=literal>eventsToEnable</tt> 
parameter are found in the <tt CLASS=literal>AWTEvent</tt> 
class; you can use any of the <tt CLASS=literal>EVENT_MASK</tt> 
constants like <tt CLASS=literal>COMPONENT_EVENT_MASK</tt>, 
<tt CLASS=literal>MOUSE_EVENT_MASK</tt>, and <tt CLASS=literal>WINDOW_EVENT_MASK</tt> 
ORed together for the events you care about. For instance, to listen for 
action events, call: </DL>
<DIV CLASS=screen>
<P>
<PRE>
enableEvents (AWTEvent.ACTION_EVENT_MASK);
</PRE>
</DIV>

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>protected final void disableEvents(long eventsToDisable) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
Using the <tt CLASS=literal>disableEvents()</tt> method 
is usually not necessary. When you remove an action listener, the <tt CLASS=literal>MenuItem</tt> 
stops listening for action events if there are no more listeners. However, 
if you need to, you can disable events explicitly by calling <tt CLASS=literal>disableEvents()</tt>. 
The settings for the <tt CLASS=literal>eventsToDisable</tt> 
parameter are found in the <tt CLASS=literal>AWTEvent</tt> 
class; you can use any of the <tt CLASS=literal>EVENT_MASK</tt> 
constants such as <tt CLASS=literal>FOCUS_EVENT_MASK</tt>, 
<tt CLASS=literal>MOUSE_MOTION_EVENT_MASK</tt>, and 
<tt CLASS=literal>ACTION_EVENT_MASK</tt> ORed together 
for the events you no longer care about. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>protected void processEvent(AWTEvent e) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>processEvent()</tt> method receives 
all <tt CLASS=literal>AWTEvent</tt>s with this <tt CLASS=literal>MenuItem</tt> 
as its target. <tt CLASS=literal>processEvent()</tt> 
then passes them along to any listeners for processing. When you subclass 
<tt CLASS=literal>MenuItem</tt>, overriding <tt CLASS=literal>processEvent()</tt> 
allows you to process all events yourself, before sending them to any listeners. 
In a way, overriding <tt CLASS=literal>processEvent()</tt> 
is like overriding <tt CLASS=literal>postEvent()</tt> 
using the 1.0 event model. 

<P CLASS=para>
If you override <tt CLASS=literal>processEvent()</tt>, 
remember to call <tt CLASS=literal>super.processEvent(e)</tt> 
last to ensure that regular event processing can occur. If you want to 
process your own events, it's a good idea to call <tt CLASS=literal>enableEvents()</tt> 
to ensure that events are delivered even in the absence of registered listeners. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>protected void processActionEvent(ItemEvent e) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>processActionEvent()</tt> method 
receives all <tt CLASS=literal>ActionEvent</tt>s with 
this <tt CLASS=literal>MenuItem</tt> as its target. 
<tt CLASS=literal>processActionEvent()</tt> then passes 
them along to any listeners for processing. When you subclass <tt CLASS=literal>MenuItem</tt>, 
overriding <tt CLASS=literal>processActionEvent()</tt> 
allows you to process all action events yourself, before sending them to 
any listeners. In a way, overriding <tt CLASS=literal>processActionEvent()</tt> 
is like overriding <tt CLASS=literal>action() </tt>using 
the 1.0 event model. 

<P CLASS=para>
If you override <tt CLASS=literal>processActionEvent()</tt>, 
remember to call the method <tt CLASS=literal>super.processActionEvent(e)</tt> 
last to ensure that regular event processing can occur. If you want to 
process your own events, it's a good idea to call <tt CLASS=literal>enableEvents()</tt> 
to ensure that events are delivered even in the absence of registered listeners. </DL>
</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch10_03.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch10_05.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>MenuShortcut</td>
<td width=171 align=center valign=top><a href="index/idx_a.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>Menu</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
